Sprite 1984

home *** CD-ROM | disk | FTP | other *** search

/ Sprite 1984 - 1993 / Sprite 1984 - 1993.iso / src / cmds / gdb-4.5 / ds3100.md / bfd / doc / bfd.info-2 < prev next >

Wrap

Text File | 1992-07-01 | 47.2 KB | 1,606 lines

Info file bfd.info, produced by Makeinfo, -*- Text -*- from input file ./bfd.texinfo. START-INFO-DIR-ENTRY * Bfd: (bfd). The Binary File Descriptor library. END-INFO-DIR-ENTRY This file documents the BFD library. Copyright (C) 1991 Free Software Foundation, Inc. Permission is granted to make and distribute verbatim copies of this manual provided the copyright notice and this permission notice are preserved on all copies. Permission is granted to copy and distribute modified versions of this manual under the conditions for verbatim copying, subject to the terms of the GNU General Public License, which includes the provision that the entire resulting derived work is distributed under the terms of a permission notice identical to this one. Permission is granted to copy and distribute translations of this manual into another language, under the above conditions for modified versions. File: bfd.info, Node: Formats, Next: Relocations, Prev: Archives, Up: BFD front end File Formats ============ A format is a BFD concept of high level file contents. The formats supported by BFD are: * The BFD may contain data, symbols, relocations and debug info. * The BFD contains other BFDs and an optional index. * The BFD contains the result of an executable core dump. `bfd_check_format' ................... *Synopsis* boolean bfd_check_format(bfd *abfd, bfd_format format); *Description* This routine is supplied a BFD and a format. It attempts to verify if the file attached to the BFD is indeed compatible with the format specified (ie, one of `bfd_object', `bfd_archive' or `bfd_core'). If the BFD has been set to a specific TARGET before the call, only the named target and format combination will be checked. If the target has not been set, or has been set to `default' then all the known target backends will be interrogated to determine a match. The function returns `true' on success, otherwise `false' with one of the following error codes: * if `format' is not one of `bfd_object', `bfd_archive'or `bfd_core'. * if an error occured during a read - even some file mismatches can cause system_call_errros * none of the backends recognised the file format * more than one backend recognised the file format. `bfd_set_format' ................. *Synopsis* boolean bfd_set_format(bfd *, bfd_format); *Description* This function sets the file format of the supplied BFD to the format requested. If the target set in the BFD does not support the format requested, the format is illegal or the BFD is not open for writing than an error occurs. `bfd_format_string' ................... *Synopsis* CONST char *bfd_format_string(bfd_format); *Description* This function takes one argument, and enumerated type (bfd_format) and returns a pointer to a const string `invalid', `object', `archive', `core' or `unknown' depending upon the value of the enumeration. File: bfd.info, Node: Relocations, Next: Core Files, Prev: Formats, Up: BFD front end Relocations =========== BFD maintains relocations in much the same was as it maintains symbols; they are left alone until required, then read in en-mass and traslated into an internal form. There is a common routine `bfd_perform_relocation' which acts upon the canonical form to to the actual fixup. Note that relocations are maintained on a per section basis, whilst symbols are maintained on a per BFD basis. All a back end has to do to fit the BFD interface is to create as many `struct reloc_cache_entry' as there are relocations in a particuar section, and fill in the right bits: * Menu: * typedef arelent:: * howto manager:: File: bfd.info, Node: typedef arelent, Next: howto manager, Prev: Relocations, Up: Relocations typedef arelent --------------- This is the structure of a relocation entry: . typedef enum bfd_reloc_status { /* No errors detected */ bfd_reloc_ok, /* The relocation was performed, but there was an overflow. */ bfd_reloc_overflow, /* The address to relocate was not within the section supplied*/ bfd_reloc_outofrange, /* Used by special functions */ bfd_reloc_continue, /* Unused */ bfd_reloc_notsupported, /* Unsupported relocation size requested. */ bfd_reloc_other, /* The symbol to relocate against was undefined.*/ bfd_reloc_undefined, /* The relocation was performed, but may not be ok - presently generated only when linking i960 coff files with i960 b.out symbols. */ bfd_reloc_dangerous } bfd_reloc_status_type; typedef struct reloc_cache_entry { /* A pointer into the canonical table of pointers */ struct symbol_cache_entry **sym_ptr_ptr; /* offset in section */ rawdata_offset address; /* addend for relocation value */ bfd_vma addend; /* Pointer to how to perform the required relocation */ CONST struct reloc_howto_struct *howto; } arelent; *Description* Here is a description of each of the fields within a relent: * The symbol table pointer points to a pointer to the symbol associated with the relocation request. This would naturally be the pointer into the table returned by the back end's get_symtab action. *Note Symbols::. The symbol is referenced through a pointer to a pointer so that tools like the linker can fix up all the symbols of the same name by modifying only one pointer. The relocation routine looks in the symbol and uses the base of the section the symbol is attached to and the value of the symbol as the initial relocation offset. If the symbol pointer is zero, then the section provided is looked up. * The address field gives the offset in bytes from the base of the section data which owns the relocation record to the first byte of relocatable information. The actual data relocated will be relative to this point - for example, a relocation type which modifies the bottom two bytes of a four byte word would not touch the first byte pointed to in a big endian world. * end to be added (!) to the relocation offset. Its interpretation is dependent upon the howto. For example, on the 68k the code: char foo[]; main() { return foo[0x12345678]; } Could be compiled into: linkw fp,#-4 moveb @#12345678,d0 extbl d0 unlk fp rts This could create a reloc pointing to foo, but leave the offset in the data (something like) RELOCATION RECORDS FOR [.text]: offset type value 00000006 32 _foo 00000000 4e56 fffc ; linkw fp,#-4 00000004 1039 1234 5678 ; moveb @#12345678,d0 0000000a 49c0 ; extbl d0 0000000c 4e5e ; unlk fp 0000000e 4e75 ; rts Using coff and an 88k, some instructions don't have enough space in them to represent the full address range, and pointers have to be loaded in two parts. So you'd get something like: or.u r13,r0,hi16(_foo+0x12345678) ld.b r2,r13,lo16(_foo+0x12345678) jmp r1 This whould create two relocs, both pointing to _foo, and with 0x12340000 in their addend field. The data would consist of: RELOCATION RECORDS FOR [.text]: offset type value 00000002 HVRT16 _foo+0x12340000 00000006 LVRT16 _foo+0x12340000 00000000 5da05678 ; or.u r13,r0,0x5678 00000004 1c4d5678 ; ld.b r2,r13,0x5678 00000008 f400c001 ; jmp r1 The relocation routine digs out the value from the data, adds it to the addend to get the original offset and then adds the value of _foo. Note that all 32 bits have to be kept around somewhere, to cope with carry from bit 15 to bit 16. On further example is the sparc and the a.out format. The sparc has a similar problem to the 88k, in that some instructions don't have room for an entire offset, but on the sparc the parts are created odd sized lumps. The designers of the a.out format chose not to use the data within the section for storing part of the offset; all the offset is kept within the reloc. Any thing in the data should be ignored. save %sp,-112,%sp sethi %hi(_foo+0x12345678),%g2 ldsb [%g2+%lo(_foo+0x12345678)],%i0 ret restore Both relocs contains a pointer to foo, and the offsets would contain junk. RELOCATION RECORDS FOR [.text]: offset type value 00000004 HI22 _foo+0x12345678 00000008 LO10 _foo+0x12345678 00000000 9de3bf90 ; save %sp,-112,%sp 00000004 05000000 ; sethi %hi(_foo+0),%g2 00000008 f048a000 ; ldsb [%g2+%lo(_foo+0)],%i0 0000000c 81c7e008 ; ret 00000010 81e80000 ; restore * The howto field can be imagined as a relocation instruction. It is a pointer to a struct which contains information on what to do with all the other information in the reloc record and data section. A back end would normally have a relocation instruction set and turn relocations into pointers to the correct structure on input - but it would be possible to create each howto field on demand. `reloc_howto_type' ................... The `reloc_howto_type' is a structure which contains all the information that BFD needs to know to tie up a back end's data. .struct symbol_cache_entry; /* Forward declaration */ typedef CONST struct reloc_howto_struct { /* The type field has mainly a documetary use - the back end can to what it wants with it, though the normally the back end's external idea of what a reloc number would be would be stored in this field. For example, the a PC relative word relocation in a coff environment would have the type 023 - because that's what the outside world calls a R_PCRWORD reloc. */ unsigned int type; /* The value the final relocation is shifted right by. This drops unwanted data from the relocation. */ unsigned int rightshift; /* The size of the item to be relocated - 0, is one byte, 1 is 2 bytes, 3 is four bytes. */ unsigned int size; /* Now obsolete */ unsigned int bitsize; /* Notes that the relocation is relative to the location in the data section of the addend. The relocation function will subtract from the relocation value the address of the location being relocated. */ boolean pc_relative; /* Now obsolete */ unsigned int bitpos; /* Now obsolete */ boolean absolute; /* Causes the relocation routine to return an error if overflow is detected when relocating. */ boolean complain_on_overflow; /* If this field is non null, then the supplied function is called rather than the normal function. This allows really strange relocation methods to be accomodated (eg, i960 callj instructions). */ bfd_reloc_status_type EXFUN ((*special_function), (bfd *abfd, arelent *reloc_entry, struct symbol_cache_entry *symbol, PTR data, asection *input_section)); /* The textual name of the relocation type. */ char *name; /* When performing a partial link, some formats must modify the relocations rather than the data - this flag signals this.*/ boolean partial_inplace; /* The src_mask is used to select what parts of the read in data are to be used in the relocation sum. Eg, if this was an 8 bit bit of data which we read and relocated, this would be 0x000000ff. When we have relocs which have an addend, such as sun4 extended relocs, the value in the offset part of a relocating field is garbage so we never use it. In this case the mask would be 0x00000000. */ bfd_word src_mask; /* The dst_mask is what parts of the instruction are replaced into the instruction. In most cases src_mask == dst_mask, except in the above special case, where dst_mask would be 0x000000ff, and src_mask would be 0x00000000. */ bfd_word dst_mask; /* When some formats create PC relative instructions, they leave the value of the pc of the place being relocated in the offset slot of the instruction, so that a PC relative relocation can be made just by adding in an ordinary offset (eg sun3 a.out). Some formats leave the displacement part of an instruction empty (eg m88k bcs), this flag signals the fact.*/ boolean pcrel_offset; } reloc_howto_type; `the HOWTO macro' ................. *Description* The HOWTO define is horrible and will go away. #define HOWTO(C, R,S,B, P, BI, ABS, O, SF, NAME, INPLACE, MASKSRC, MASKDST, PC) \ {(unsigned)C,R,S,B, P, BI, ABS,O,SF,NAME,INPLACE,MASKSRC,MASKDST,PC} *Description* And will be replaced with the totally magic way. But for the moment, we are compatible, so do it this way.. #define NEWHOWTO( FUNCTION, NAME,SIZE,REL,IN) HOWTO(0,0,SIZE,0,REL,0,false,false,FUNCTION, NAME,false,0,0,IN) *Description* Helper routine to turn a symbol into a relocation value. #define HOWTO_PREPARE(relocation, symbol) \ { \ if (symbol != (asymbol *)NULL) { \ if (symbol->section == &bfd_com_section) { \ relocation = 0; \ } \ else { \ relocation = symbol->value; \ } \ } \ } `reloc_chain' .............. *Description* How relocs are tied together typedef unsigned char bfd_byte; typedef struct relent_chain { arelent relent; struct relent_chain *next; } arelent_chain; `bfd_perform_relocation' ......................... *Synopsis* bfd_reloc_status_type bfd_perform_relocation (bfd * abfd, arelent *reloc_entry, PTR data, asection *input_section, bfd *output_bfd); *Description* If an output_bfd is supplied to this function the generated image will be relocatable, the relocations are copied to the output file after they have been changed to reflect the new state of the world. There are two ways of reflecting the results of partial linkage in an output file; by modifying the output data in place, and by modifying the relocation record. Some native formats (eg basic a.out and basic coff) have no way of specifying an addend in the relocation type, so the addend has to go in the output data. This is no big deal since in these formats the output data slot will always be big enough for the addend. Complex reloc types with addends were invented to solve just this problem. File: bfd.info, Node: howto manager, Prev: typedef arelent, Up: Relocations The howto manager ================= When an application wants to create a relocation, but doesn't know what the target machine might call it, it can find out by using this bit of code. `bfd_reloc_code_type' ..................... *Description* The insides of a reloc code . typedef enum bfd_reloc_code_real { /* 16 bits wide, simple reloc */ BFD_RELOC_16, /* 8 bits wide, but used to form an address like 0xffnn */ BFD_RELOC_8_FFnn, /* 8 bits wide, simple */ BFD_RELOC_8, /* 8 bits wide, pc relative */ BFD_RELOC_8_PCREL, /* The type of reloc used to build a contructor table - at the moment probably a 32 bit wide abs address, but the cpu can choose. */ BFD_RELOC_CTOR } bfd_reloc_code_real_type; bfd_reloc_type_lookup ===================== *Synopsis* CONST struct reloc_howto_struct * bfd_reloc_type_lookup (CONST bfd_arch_info_type *arch, bfd_reloc_code_type code); *Description* This routine returns a pointer to a howto struct which when invoked, will perform the supplied relocation on data from the architecture noted. `bfd_default_reloc_type_lookup' ............................... *Synopsis* CONST struct reloc_howto_struct *bfd_default_reloc_type_lookup (CONST struct bfd_arch_info *, bfd_reloc_code_type code); *Description* Provides a default relocation lookuperer for any architectue `bfd_generic_relax_section' ........................... *Synopsis* boolean bfd_generic_relax_section (bfd *abfd, asection *section, asymbol **symbols); *Description* Provides default handling for relaxing for back ends which don't do relaxing - ie does nothing `bfd_generic_get_relocated_section_contents' ............................................ *Synopsis* bfd_byte * bfd_generic_get_relocated_section_contents(bfd *abfd, struct bfd_seclet_struct *seclet) *Description* Provides default handling of relocation effort for back ends which can't be bothered to do it efficiently. File: bfd.info, Node: Core Files, Next: Targets, Prev: Relocations, Up: BFD front end Core files ========== *Description* Buff output this facinating topic `bfd_core_file_failing_command' ............................... *Synopsis* CONST char *bfd_core_file_failing_command(bfd *); *Description* Returns a read-only string explaining what program was running when it failed and produced the core file being read `bfd_core_file_failing_signal' .............................. *Synopsis* int bfd_core_file_failing_signal(bfd *); *Description* Returns the signal number which caused the core dump which generated the file the BFD is attached to. `core_file_matches_executable_p' ................................ *Synopsis* boolean core_file_matches_executable_p (bfd *core_bfd, bfd *exec_bfd); *Description* Returns `true' if the core file attached to CORE_BFD was generated by a run of the executable file attached to EXEC_BFD, or else `false'. File: bfd.info, Node: Targets, Next: Architectures, Prev: Core Files, Up: BFD front end Targets ======= *Description* Each port of BFD to a different machine requries the creation of a target back end. All the back end provides to the root part of BFD is a structure containing pointers to functions which perform certain low level operations on files. BFD translates the applications's requests through a pointer into calls to the back end routines. When a file is opened with `bfd_openr', its format and target are unknown. BFD uses various mechanisms to determine how to interpret the file. The operations performed are: * `new_bfd', then `bfd_find_target' is called with the target string supplied to `bfd_openr' and the new BFD pointer. * it looks up the environment variable `GNUTARGET' and uses that as the target string. * `default', then the first item in the target vector is used as the target type. *Note bfd_target::. * one by one, until a match on target name is found. When found, that is used. * `bfd_openr'. * `bfd_open_file', and returns the BFD. Once the BFD has been opened and the target selected, the file format may be determined. This is done by calling `bfd_check_format' on the BFD with a suggested format. The routine returns `true' when the application guesses right. * Menu: * bfd_target:: File: bfd.info, Node: bfd_target, Prev: Targets, Up: Targets bfd_target ---------- *Description* This structure contains everything that BFD knows about a target. It includes things like its byte order, name, what routines to call to do various operations, etc. Every BFD points to a target structure with its `xvec' member. Shortcut for declaring fields which are prototyped function pointers, while avoiding anguish on compilers that don't support protos. #define SDEF(ret, name, arglist) \ PROTO(ret,(*name),arglist) #define SDEF_FMT(ret, name, arglist) \ PROTO(ret,(*name[bfd_type_end]),arglist) These macros are used to dispatch to functions through the bfd_target vector. They are used in a number of macros further down in `bfd.h', and are also used when calling various routines by hand inside the BFD implementation. The "arglist" argument must be parenthesized; it contains all the arguments to the called function. #define BFD_SEND(bfd, message, arglist) \ ((*((bfd)->xvec->message)) arglist) For operations which index on the BFD format #define BFD_SEND_FMT(bfd, message, arglist) \ (((bfd)->xvec->message[(int)((bfd)->format)]) arglist) This is the struct which defines the type of BFD this is. The `xvec' member of the struct `bfd' itself points here. Each module that implements access to a different target under BFD, defines one of these. FIXME, these names should be rationalised with the names of the entry points which call them. Too bad we can't have one macro to define them both! typedef struct bfd_target { identifies the kind of target, eg SunOS4, Ultrix, etc char *name; The "flavour" of a back end is a general indication about the contents of a file. enum target_flavour { bfd_target_unknown_flavour, bfd_target_aout_flavour, bfd_target_coff_flavour, bfd_target_elf_flavour, bfd_target_ieee_flavour, bfd_target_oasys_flavour, bfd_target_srec_flavour} flavour; The order of bytes within the data area of a file. boolean byteorder_big_p; The order of bytes within the header parts of a file. boolean header_byteorder_big_p; This is a mask of all the flags which an executable may have set - from the set `NO_FLAGS', `HAS_RELOC', ...`D_PAGED'. flagword object_flags; This is a mask of all the flags which a section may have set - from the set `SEC_NO_FLAGS', `SEC_ALLOC', ...`SET_NEVER_LOAD'. flagword section_flags; The pad character for filenames within an archive header. char ar_pad_char; The maximum number of characters in an archive header. unsigned short ar_max_namelen; The minimum alignment restriction for any section. unsigned int align_power_min; Entries for byte swapping for data. These are different to the other entry points, since they don't take BFD as first arg. Certain other handlers could do the same. SDEF (bfd_vma, bfd_getx64, (bfd_byte *)); SDEF (void, bfd_putx64, (bfd_vma, bfd_byte *)); SDEF (bfd_vma, bfd_getx32, (bfd_byte *)); SDEF (void, bfd_putx32, (bfd_vma, bfd_byte *)); SDEF (bfd_vma, bfd_getx16, (bfd_byte *)); SDEF (void, bfd_putx16, (bfd_vma, bfd_byte *)); Byte swapping for the headers SDEF (bfd_vma, bfd_h_getx64, (bfd_byte *)); SDEF (void, bfd_h_putx64, (bfd_vma, bfd_byte *)); SDEF (bfd_vma, bfd_h_getx32, (bfd_byte *)); SDEF (void, bfd_h_putx32, (bfd_vma, bfd_byte *)); SDEF (bfd_vma, bfd_h_getx16, (bfd_byte *)); SDEF (void, bfd_h_putx16, (bfd_vma, bfd_byte *)); Format dependent routines, these turn into vectors of entry points within the target vector structure; one for each format to check. Check the format of a file being read. Return bfd_target * or zero. SDEF_FMT (struct bfd_target *, _bfd_check_format, (bfd *)); Set the format of a file being written. SDEF_FMT (boolean, _bfd_set_format, (bfd *)); Write cached information into a file being written, at bfd_close. SDEF_FMT (boolean, _bfd_write_contents, (bfd *)); The following functions are defined in `JUMP_TABLE'. The idea is that the back end writer of `foo' names all the routines `foo_'ENTRY_POINT, `JUMP_TABLE' will built the entries in this structure in the right order. Core file entry points SDEF (char *, _core_file_failing_command, (bfd *)); SDEF (int, _core_file_failing_signal, (bfd *)); SDEF (boolean, _core_file_matches_executable_p, (bfd *, bfd *)); Archive entry points SDEF (boolean, _bfd_slurp_armap, (bfd *)); SDEF (boolean, _bfd_slurp_extended_name_table, (bfd *)); SDEF (void, _bfd_truncate_arname, (bfd *, CONST char *, char *)); SDEF (boolean, write_armap, (bfd *arch, unsigned int elength, struct orl *map, unsigned int orl_count, int stridx)); Standard stuff. SDEF (boolean, _close_and_cleanup, (bfd *)); SDEF (boolean, _bfd_set_section_contents, (bfd *, sec_ptr, PTR, file_ptr, bfd_size_type)); SDEF (boolean, _bfd_get_section_contents, (bfd *, sec_ptr, PTR, file_ptr, bfd_size_type)); SDEF (boolean, _new_section_hook, (bfd *, sec_ptr)); Symbols and reloctions SDEF (unsigned int, _get_symtab_upper_bound, (bfd *)); SDEF (unsigned int, _bfd_canonicalize_symtab, (bfd *, struct symbol_cache_entry **)); SDEF (unsigned int, _get_reloc_upper_bound, (bfd *, sec_ptr)); SDEF (unsigned int, _bfd_canonicalize_reloc, (bfd *, sec_ptr, arelent **, struct symbol_cache_entry**)); SDEF (struct symbol_cache_entry *, _bfd_make_empty_symbol, (bfd *)); SDEF (void, _bfd_print_symbol, (bfd *, PTR, struct symbol_cache_entry *, bfd_print_symbol_type)); #define bfd_print_symbol(b,p,s,e) BFD_SEND(b, _bfd_print_symbol, (b,p,s,e)) SDEF (alent *, _get_lineno, (bfd *, struct symbol_cache_entry *)); SDEF (boolean, _bfd_set_arch_mach, (bfd *, enum bfd_architecture, unsigned long)); SDEF (bfd *, openr_next_archived_file, (bfd *arch, bfd *prev)); SDEF (boolean, _bfd_find_nearest_line, (bfd *abfd, struct sec *section, struct symbol_cache_entry **symbols,bfd_vma offset, CONST char **file, CONST char **func, unsigned int *line)); SDEF (int, _bfd_stat_arch_elt, (bfd *, struct stat *)); SDEF (int, _bfd_sizeof_headers, (bfd *, boolean)); SDEF (void, _bfd_debug_info_start, (bfd *)); SDEF (void, _bfd_debug_info_end, (bfd *)); SDEF (void, _bfd_debug_info_accumulate, (bfd *, struct sec *)); SDEF (bfd_byte *, _bfd_get_relocated_section_contents, (bfd*,struct bfd_seclet_struct *)); SDEF (boolean,_bfd_relax_section,(bfd *, struct sec *, struct symbol_cache_entry **)); Special entry points for gdb to swap in coff symbol table parts SDEF(void, _bfd_coff_swap_aux_in,( bfd *abfd , PTR ext, int type, int class , PTR in)); SDEF(void, _bfd_coff_swap_sym_in,( bfd *abfd , PTR ext, PTR in)); SDEF(void, _bfd_coff_swap_lineno_in, ( bfd *abfd, PTR ext, PTR in)); Special entry points for gas to swap coff parts SDEF(unsigned int, _bfd_coff_swap_aux_out,( bfd *abfd, PTR in, int type, int class, PTR ext)); SDEF(unsigned int, _bfd_coff_swap_sym_out,( bfd *abfd, PTR in, PTR ext)); SDEF(unsigned int, _bfd_coff_swap_lineno_out,( bfd *abfd, PTR in, PTR ext)); SDEF(unsigned int, _bfd_coff_swap_reloc_out,( bfd *abfd, PTR src, PTR dst)); SDEF(unsigned int, _bfd_coff_swap_filehdr_out,( bfd *abfd, PTR in, PTR out)); SDEF(unsigned int, _bfd_coff_swap_aouthdr_out,( bfd *abfd, PTR in, PTR out)); SDEF(unsigned int, _bfd_coff_swap_scnhdr_out,( bfd *abfd, PTR in, PTR out)); } bfd_target; `bfd_find_target' .................. *Description* Returns a pointer to the transfer vector for the object target named target_name. If target_name is NULL, chooses the one in the environment variable GNUTARGET; if that is null or not defined thenthe first entry in the target list is chosen. Passing in the string "default" or setting the environment variable to "default" will cause the first entry in the target list to be returned, and "target_defaulted" will be set in the BFD. This causes `bfd_check_format' to loop over all the targets to find the one that matches the file being read. *Synopsis* bfd_target *bfd_find_target(CONST char *, bfd *); `bfd_target_list' ................. *Description* This function returns a freshly malloced NULL-terminated vector of the names of all the valid BFD targets. Do not modify the names *Synopsis* CONST char **bfd_target_list(void); File: bfd.info, Node: Architectures, Next: Opening and Closing, Prev: Targets, Up: BFD front end Architectures ============= BFD's idea of an architecture is implimented in `archures.c'. BFD keeps one atom in a BFD describing the architecture of the data attached to the BFD; a pointer to a `bfd_arch_info_type'. Pointers to structures can be requested independently of a bfd so that an architecture's information can be interrogated without access to an open bfd. The arch information is provided by each architecture package. The set of default architectures is selected by the #define `SELECT_ARCHITECTURES'. This is normally set up in the `config\/h\-' file of your choice. If the name is not defined, then all the architectures supported are included. When BFD starts up, all the architectures are called with an initialize method. It is up to the architecture back end to insert as many items into the list of arches as it wants to, generally this would be one for each machine and one for the default case (an item with a machine field of 0). bfd_architecture ---------------- *Description* This enum gives the object file's CPU architecture, in a global sense. E.g. what processor family does it belong to? There is another field, which indicates what processor within the family is in use. The machine gives a number which distingushes different versions of the architecture, containing for example 2 and 3 for Intel i960 KA and i960 KB, and 68020 and 68030 for Motorola 68020 and 68030. enum bfd_architecture { bfd_arch_unknown, /* File arch not known */ bfd_arch_obscure, /* Arch known, not one of these */ bfd_arch_m68k, /* Motorola 68xxx */ bfd_arch_vax, /* DEC Vax */ bfd_arch_i960, /* Intel 960 */ /* The order of the following is important. lower number indicates a machine type that only accepts a subset of the instructions available to machines with higher numbers. The exception is the "ca", which is incompatible with all other machines except "core". */ #define bfd_mach_i960_core 1 #define bfd_mach_i960_ka_sa 2 #define bfd_mach_i960_kb_sb 3 #define bfd_mach_i960_mc 4 #define bfd_mach_i960_xa 5 #define bfd_mach_i960_ca 6 bfd_arch_a29k, /* AMD 29000 */ bfd_arch_sparc, /* SPARC */ bfd_arch_mips, /* MIPS Rxxxx */ bfd_arch_i386, /* Intel 386 */ bfd_arch_ns32k, /* National Semiconductor 32xxx */ bfd_arch_tahoe, /* CCI/Harris Tahoe */ bfd_arch_i860, /* Intel 860 */ bfd_arch_romp, /* IBM ROMP PC/RT */ bfd_arch_alliant, /* Alliant */ bfd_arch_convex, /* Convex */ bfd_arch_m88k, /* Motorola 88xxx */ bfd_arch_pyramid, /* Pyramid Technology */ bfd_arch_h8300, /* Hitachi H8/300 */ bfd_arch_rs6000, /* IBM RS/6000 */ bfd_arch_last }; bfd_arch_info -------------- *Description* This structure contains information on architectures for use within BFD. typedef int bfd_reloc_code_type; typedef struct bfd_arch_info { int bits_per_word; int bits_per_address; int bits_per_byte; enum bfd_architecture arch; long mach; char *arch_name; CONST char *printable_name; /* true if this is the default machine for the architecture */ unsigned int section_align_power; boolean the_default; CONST struct bfd_arch_info * EXFUN((*compatible), (CONST struct bfd_arch_info *a, CONST struct bfd_arch_info *b)); boolean EXFUN((*scan),(CONST struct bfd_arch_info *,CONST char *)); unsigned int EXFUN((*disassemble),(bfd_vma addr, CONST char *data, PTR stream)); CONST struct reloc_howto_struct *EXFUN((*reloc_type_lookup), (CONST struct bfd_arch_info *, bfd_reloc_code_type code)); struct bfd_arch_info *next; } bfd_arch_info_type; `bfd_printable_name' ..................... *Synopsis* CONST char *bfd_printable_name(bfd *abfd); *Description* Return a printable string representing the architecture and machine from the pointer to the arch info structure `bfd_scan_arch' ............... *Synopsis* bfd_arch_info_type *bfd_scan_arch(CONST char *); *Description* This routine is provided with a string and tries to work out if bfd supports any cpu which could be described with the name provided. The routine returns a pointer to an arch_info structure if a machine is found, otherwise NULL. `bfd_arch_get_compatible' ......................... *Synopsis* CONST bfd_arch_info_type *bfd_arch_get_compatible( CONST bfd *abfd, CONST bfd *bbfd); *Description* This routine is used to determine whether two BFDs' architectures and achine types are compatible. It calculates the lowest common denominator between the two architectures and machine types implied by the BFDs and returns a pointer to an arch_info structure describing the compatible machine. `bfd_default_arch_struct' ......................... *Description* The `bfd_default_arch_struct' is an item of `bfd_arch_info_type' which has been initialized to a fairly generic state. A BFD starts life by pointing to this structure, until the correct back end has determined the real architecture of the file. extern bfd_arch_info_type bfd_default_arch_struct; `bfd_set_arch_info' .................... *Synopsis* void bfd_set_arch_info(bfd *, bfd_arch_info_type *); `bfd_default_set_arch_mach' ........................... *Synopsis* boolean bfd_default_set_arch_mach(bfd *abfd, enum bfd_architecture arch, unsigned long mach); *Description* Set the architecture and machine type in a bfd. This finds the correct pointer to structure and inserts it into the arch_info pointer. `bfd_get_arch' .............. *Synopsis* enum bfd_architecture bfd_get_arch(bfd *abfd); *Description* Returns the enumerated type which describes the supplied bfd's architecture `bfd_get_mach' .............. *Synopsis* unsigned long bfd_get_mach(bfd *abfd); *Description* Returns the long type which describes the supplied bfd's machine `bfd_arch_bits_per_byte' ........................ *Synopsis* unsigned int bfd_arch_bits_per_byte(bfd *abfd); *Description* Returns the number of bits in one of the architectures bytes `bfd_arch_bits_per_address' ........................... *Synopsis* unsigned int bfd_arch_bits_per_address(bfd *abfd); *Description* Returns the number of bits in one of the architectures addresses `bfd_arch_init' ............... *Synopsis* void bfd_arch_init(void); *Description* This routine initializes the architecture dispatch table by calling all installed architecture packages and getting them to poke around. `bfd_arch_linkin' ................. *Synopsis* void bfd_arch_linkin(bfd_arch_info_type *); *Description* Link the provided arch info structure into the list `bfd_default_compatible' ........................ *Synopsis* CONST bfd_arch_info_type *bfd_default_compatible (CONST bfd_arch_info_type *a, CONST bfd_arch_info_type *b); *Description* The default function for testing for compatibility. `bfd_default_scan' .................. *Synopsis* boolean bfd_default_scan(CONST struct bfd_arch_info *, CONST char *); *Description* The default function for working out whether this is an architecture hit and a machine hit. `bfd_get_arch_info' ................... *Synopsis* bfd_arch_info_type * bfd_get_arch_info(bfd *); `bfd_lookup_arch' ................. *Synopsis* bfd_arch_info_type *bfd_lookup_arch (enum bfd_architecture arch, long machine); *Description* Look for the architecure info struct which matches the arguments given. A machine of 0 will match the machine/architecture structure which marks itself as the default. `bfd_printable_arch_mach' ......................... *Synopsis* CONST char * bfd_printable_arch_mach (enum bfd_architecture arch, unsigned long machine); *Description* Return a printable string representing the architecture and machine type. NB. The use of this routine is depreciated. File: bfd.info, Node: Opening and Closing, Next: Constructors, Prev: Architectures, Up: BFD front end Opening and Closing BFDs ======================== `bfd_openr' ............ *Synopsis* bfd *bfd_openr(CONST char *filename, CONST char*target); *Description* This function opens the file supplied (using `fopen') with the target supplied, it returns a pointer to the created BFD. If NULL is returned then an error has occured. Possible errors are `no_memory', `invalid_target' or `system_call' error. `bfd_fdopenr' ............. *Synopsis* bfd *bfd_fdopenr(CONST char *filename, CONST char *target, int fd); *Description* bfd_fdopenr is to bfd_fopenr much like fdopen is to fopen. It opens a BFD on a file already described by the FD supplied. Possible errors are no_memory, invalid_target and system_call error. `bfd_openw' ........... *Synopsis* bfd *bfd_openw(CONST char *filename, CONST char *target); *Description* Creates a BFD, associated with file FILENAME, using the file format TARGET, and returns a pointer to it. Possible errors are system_call_error, no_memory, invalid_target. `bfd_close' ........... *Synopsis* boolean bfd_close(bfd *); *Description* This function closes a BFD. If the BFD was open for writing, then pending operations are completed and the file written out and closed. If the created file is executable, then `chmod' is called to mark it as such. All memory attached to the BFD's obstacks is released. *Returns* `true' is returned if all is ok, otherwise `false'. `bfd_close_all_done' .................... *Synopsis* boolean bfd_close_all_done(bfd *); *Description* This function closes a BFD. It differs from `bfd_close' since it does not complete any pending operations. This routine would be used if the application had just used BFD for swapping and didn't want to use any of the writing code. If the created file is executable, then `chmod' is called to mark it as such. All memory attached to the BFD's obstacks is released. *Returns* `true' is returned if all is ok, otherwise `false'. *Synopsis* bfd_size_type bfd_alloc_size(bfd *abfd); *Description* Return the number of bytes in the obstacks connected to the supplied BFD. `bfd_create' ............ *Synopsis* bfd *bfd_create(CONST char *filename, bfd *template); *Description* This routine creates a new BFD in the manner of `bfd_openw', but without opening a file. The new BFD takes the target from the target used by TEMPLATE. The format is always set to `bfd_object'. `bfd_alloc_by_size_t' ..................... *Synopsis* PTR bfd_alloc_by_size_t(bfd *abfd, size_t wanted); *Description* This function allocates a block of memory in the obstack attatched to `abfd' and returns a pointer to it. File: bfd.info, Node: Constructors, Next: Internal, Prev: Opening and Closing, Up: BFD front end Constructors ============ Classes in C++ have 'constructors' and 'destructors'. These are functions which are called automatically by the language whenever data of a class is created or destroyed. Class data which is static data may also be have a type which requires 'construction', the contructor must be called before the data can be referenced, so the contructor must be called before the program begins. The common solution to this problem is for the compiler to call a magic function as the first statement `main'. This magic function, (often called `__main') runs around calling the constructors for all the things needing it. With COFF the compile has a bargain with the linker et al. All constructors are given strange names, for example `__GLOBAL__$I$foo' might be the label of a contructor for the class FOO. The solution on unfortunate systems (most system V machines) is to perform a partial link on all the .o files, do an `nm' on the result, run `awk' or some such over the result looking for strange `__GLOBAL__$' symbols, generate a C program from this, compile it and link with the partially linked input. This process is usually called `collect'. Some versions of `a.out' use something called the `set_vector' mechanism. The constructor symbols are output from the compiler with a special stab code saying that they are constructors, and the linker can deal with them directly. BFD allows applications (ie the linker) to deal with constructor information independently of their external implimentation by providing a set of entry points for the indiviual object back ends to call which maintains a database of the contructor information. The application can interrogate the database to find out what it wants. The construction data essential for the linker to be able to perform its job are: * The asymbol of the contructor entry point contains all the information necessary to call the function. * The type of symbol, ie is it a contructor, a destructor or something else someone dreamed up to make our lives difficult. This module takes this information and then builds extra sections attached to the bfds which own the entry points. It creates these sections as if they were tables of pointers to the entry points, and builds relocation entries to go with them so that the tables can be relocated along with the data they reference. These sections are marked with a special bit (`SEC_CONSTRUCTOR') which the linker notices and do with what it wants. `bfd_constructor_entry ' ......................... *Synopsis* void bfd_constructor_entry(bfd *abfd, asymbol **symbol_ptr_ptr, CONST char*type); *Description* This function is called with an a symbol describing the function to be called, an string which descibes the xtor type, eg something like "CTOR" or "DTOR" would be fine. And the bfd which owns the function. Its duty is to create a section called "CTOR" or "DTOR" or whatever if the bfd doesn't already have one, and grow a relocation table for the entry points as they accumulate. File: bfd.info, Node: Internal, Next: File Caching, Prev: Constructors, Up: BFD front end libbfd ====== *Description* This file contains various routines which are used within BFD. They are not intended for export, but are documented here for completeness. `bfd_xmalloc' ............. *Synopsis* PTR bfd_xmalloc( bfd_size_type size); *Description* Like malloc, but exit if no more memory. `bfd_write_bigendian_4byte_int' ............................... *Synopsis* void bfd_write_bigendian_4byte_int(bfd *abfd, int i); *Description* Writes a 4 byte integer to the outputing bfd, in big endian mode regardless of what else is going on. This is usefull in archives. `bfd_put_size' .............. `bfd_get_size' .............. *Description* These macros as used for reading and writing raw data in sections; each access (except for bytes) is vectored through the target format of the BFD and mangled accordingly. The mangling performs any necessary endian translations and removes alignment restrictions. #define bfd_put_8(abfd, val, ptr) \ (*((char *)ptr) = (char)val) #define bfd_get_8(abfd, ptr) \ (*((char *)ptr)) #define bfd_put_16(abfd, val, ptr) \ BFD_SEND(abfd, bfd_putx16, (val,ptr)) #define bfd_get_16(abfd, ptr) \ BFD_SEND(abfd, bfd_getx16, (ptr)) #define bfd_put_32(abfd, val, ptr) \ BFD_SEND(abfd, bfd_putx32, (val,ptr)) #define bfd_get_32(abfd, ptr) \ BFD_SEND(abfd, bfd_getx32, (ptr)) #define bfd_put_64(abfd, val, ptr) \ BFD_SEND(abfd, bfd_putx64, (val, ptr)) #define bfd_get_64(abfd, ptr) \ BFD_SEND(abfd, bfd_getx64, (ptr)) `bfd_h_put_size' ................. `bfd_h_get_size' ................ *Description* These macros have the same function as their `bfd_get_x' bretherin, except that they are used for removing information for the header records of object files. Believe it or not, some object files keep their header records in big endian order, and their data in little endan order. #define bfd_h_put_8(abfd, val, ptr) \ (*((char *)ptr) = (char)val) #define bfd_h_get_8(abfd, ptr) \ (*((char *)ptr)) #define bfd_h_put_16(abfd, val, ptr) \ BFD_SEND(abfd, bfd_h_putx16,(val,ptr)) #define bfd_h_get_16(abfd, ptr) \ BFD_SEND(abfd, bfd_h_getx16,(ptr)) #define bfd_h_put_32(abfd, val, ptr) \ BFD_SEND(abfd, bfd_h_putx32,(val,ptr)) #define bfd_h_get_32(abfd, ptr) \ BFD_SEND(abfd, bfd_h_getx32,(ptr)) #define bfd_h_put_64(abfd, val, ptr) \ BFD_SEND(abfd, bfd_h_putx64,(val, ptr)) #define bfd_h_get_64(abfd, ptr) \ BFD_SEND(abfd, bfd_h_getx64,(ptr)) `bfd_log2' ........... *Description* Return the log base 2 of the value supplied, rounded up. eg an arg of 1025 would return 11. *Synopsis* bfd_vma bfd_log2(bfd_vma x); File: bfd.info, Node: File Caching, Prev: Internal, Up: BFD front end File Caching ============ The file caching mechanism is embedded within BFD and allows the application to open as many BFDs as it wants without regard to the underlying operating system's file descriptor limit (often as low as 20 open files). The module in `cache.c' maintains a least recently used list of `BFD_CACHE_MAX_OPEN' files, and exports the name `bfd_cache_lookup' which runs around and makes sure that the required BFD is open. If not, then it chooses a file to close, closes it and opens the one wanted, returning its file handle. `BFD_CACHE_MAX_OPEN macro' .......................... *Description* The maxiumum number of files which the cache will keep open at one time. #define BFD_CACHE_MAX_OPEN 10 `bfd_last_cache' ................. *Synopsis* extern bfd *bfd_last_cache; *Description* Zero, or a pointer to the topmost BFD on the chain. This is used by the `bfd_cache_lookup' macro in `libbfd.h' to determine when it can avoid a function call. `bfd_cache_lookup' .................. *Description* Checks to see if the required BFD is the same as the last one looked up. If so then it can use the iostream in the BFD with impunity, since it can't have changed since the last lookup, otherwise it has to perform the complicated lookup function #define bfd_cache_lookup(x) \ ((x)==bfd_last_cache? \ (FILE*)(bfd_last_cache->iostream): \ bfd_cache_lookup_worker(x)) `bfd_cache_init' ................. *Synopsis* void bfd_cache_init (bfd *); *Description* Initialize a BFD by putting it on the cache LRU. `bfd_cache_close' ................. *Description* Remove the BFD from the cache. If the attached file is open, then close it too. *Synopsis* void bfd_cache_close (bfd *); `bfd_open_file' ............... *Description* Call the OS to open a file for this BFD. Returns the FILE * (possibly null) that results from this operation. Sets up the BFD so that future accesses know the file is open. If the FILE returned is null, then there is won't have been put in the cache, so it won't have to be removed from it. *Synopsis* FILE* bfd_open_file(bfd *); `bfd_cache_lookup_worker' ......................... *Description* Called when the macro `bfd_cache_lookup' fails to find a quick answer. Finds a file descriptor for this BFD. If necessary, it open it. If there are already more than BFD_CACHE_MAX_OPEN files open, it trys to close one first, to avoid running out of file descriptors. *Synopsis* FILE *bfd_cache_lookup_worker(bfd *); File: bfd.info, Node: BFD back end, Next: Index, Prev: BFD front end, Up: Top BFD back end ************ * Menu: * What to put where:: * aout :: a.out backends * coff :: coff backends File: bfd.info, Node: What to Put Where, Next: aout, Prev: BFD back end, Up: BFD back end All of BFD lives in one directory.